How to use

Contents

Setup
edgar:scaffold
Customize
Test

Recent Updates
How to use	2012/12/23
Edgar Model Convention	2012/09/28
Support and Consulting	2012/09/19
Feature	2012/09/19
index	2012/09/19

Japanese

[+] [-] 1. Setup

create 'my_app', where my_app is assumed as your application name.
```
$ cd MY_PROJECT_DIR
$ rails new my_app -d postgresql
$ cd my_app
```
- It would be good to commit initial files at this point by:
```
$ git init
$ git add .
$ git commit -v
```

setup 'Edgar' plugin. Edgar has not yet been 'gem'ified so that please follow the steps below:

put 'edgar' plugin just under the directory:

$ git clone git://jjedgar.git.sourceforge.net/gitroot/jjedgar/edgar2

add the following entry at Gemfile:

gem 'jquery-ui-rails'
gem 'edgar', path: 'edgar2'
gem 'rails-i18n'
gem 'will_paginate',  '~> 3.0.0'
gem 'remotipart',     '~> 1.0.2'
gem 'bcrypt-ruby',    require: "bcrypt"
gem 'acts_as_tree',   '~> 1.1.0'
group :development do
  gem 'yard'
  gem 'rails-erd'
end

and run:

$ bundle install

setup DB

setup config

$ $EDITOR config/database.yml   # config database

copy edgar migration files to MyApp
```
$ rake edgar_engine:install:migrations
```

create DB

$ rake db:create
$ rake db:migrate
$ rake db:setup

setup MyApp to include Edgar
1. add the following at app/controllers/application_controller.rb:
```
include Edgar::ControllerMixinForApp  
include Edgar::AuthenticationMixin
before_filter :require_login
```
2. add the following at app/helper/application_helper.rb:
```
include EdgarHelper
```
3. add the followings at app/assets/javascripts/application.js:
```
//= require jquery.ui.dialog
//= require jquery.ui.datepicker
//= require jquery.remotipart
//= require edgar/base
//= require edgar/menu
//= require edgar/operator_selection
```
4. add the followings at app/assets/stylesheets/application.css:
```
*= require jquery.ui.dialog
*= require jquery.ui.datepicker
*= require edgar/base
*= require edgar/menu
```
5. enable session_store at config/initializers/session_store.rb by uncomment the following line:
```
MyApp::Application.config.session_store :active_record_store
```
  (NOTE: execution 'rake edgar_engine:install:migrations' above already generates session table so that no migration here is necessary)
6. At this time, MyApp server should work with minimum (but right) configration. Please start server:
```
$ rails server
```
  And access http://localhost:3000 by your browser. If you can see Rails logo, that's fine for now. Otherwise, something is wrong so that go back to the previous step and check.
setup cron job

There are several cron jobs as follows:
1. session clean-up cron
2. csv workfile clean-up cron
copy lib/edgar/templates/cron in the repository to /etc/cron.d/ and customize it to do these jobs.

[+] [-] 2. edgar:scaffold

Let me assume here to develop Product and Order models, controllers, and views. Where, Product:Order = 1:many relations.

scaffold 'Product' model by edgar:scaffold
1. use edgar:scaffold, which is like scaffold with Ajax CRUD and more:
```
$ rails generate edgar:scaffold Product name:string price:integer
$ rake db:migrate
```
  - Unlike plain scaffold, edgar:scaffold doesn't generate view files because default uses Edgar plugin's view files. Of course, controller specific view files can be created. Please follow Rails3 view file search logic.
2. create layout
  1. create application layout. One easy way is:
```
$ cp edgar2/test/dummy/app/views/layouts/application.html.erb app/views/layouts/
```
  2. create login layout, which is a login specific layout used at Edgar::SssnsController. One easy way is:
```
$ cp edgar2/test/dummy/app/views/layouts/login.html.erb app/views/layouts/
```
3. create menu config. One way is as follows:
```
$ mkdir config/edgar
$ cp edgar2/test/dummy/config/edgar/menu_config.rb config/edgar/
```
  edit config/edgar/menu_config.rb to add 'products' entry like the followings:
```
module Edgar::MenuConfig
  def top
    ...
    'products',
    '_separator',
    ...
end
```
  ('authors' and 'books' are for just Edgar engine's dummy app. Please delete them.)
4. load seed data. There could be several ways as follows:
  - For example, root user and its super-capability is seeded by:
```
$ cp edgar2/db/seeds.rb db/
$ rake db:seed
```
  - Or, load Edgar plugin's test fixtures as sample data as follows:
```
$ cd edgar2
$ tar cvf /tmp/x.tar test/fixtures/edgar*
$ cd -                        # go back to previous (should be Rails root)
$ tar xvf /tmp/x.tar          # copy edgar2/test/fixtures/edgar* to test/fixtures/edgar*
$ rake db:fixtures:load       # load test/fixtures/ to development DB
```
5. re--run server and access http://localhost:3000/products Where login id/password is root/root in this example.
Another example is 'Order' model which has many:1 relationship between Product. How product-selection popup works on Order screen will be shown.
1. run edgar:scaffold as:
```
$ rails generate edgar:scaffold Order name:string product_id:integer quantity:integer
$ rake db:migrate
```
2. establish relation between Product and Order:
  - At Product, put 'has_many :orders'
  - At Order, put 'belongs_to :product'
3. add 'orders' entry in menu config file config/edgar/menu_config.rb as:
```
module Edgar::MenuConfig
  def top
   ...
    'products',
    'orders',
    '_separator',
   ...
end
```
4. re-run server (since config is modified) and access it. You will see product-selection-popup works on Order entry form.

[+] [-] 3. Customize

Edgar supports the following levels of customization (from the easiest level to the highest level):

[+] [-] 3.1. Add column

Use Rails 'migration' to add any number of columns (actually limited by DBMS). The added columns are automatically displayed at list, form, search-form, and popup-list as default behavior. Of course, it is controllable which column is displayed or not. See 'Add model' section later.

Following example shows how to change Customer model's name column to first_name and last_name:

Generate migration and edit it (following shows vi, but of course you can use any favorite editor):

$ rails generate migration change_name_of_customers
$ vi db/migrate/YYYYMMDDNNNNNN_change_name_of_customers.rb  # YYYYMMDDNNNNNN is just sample, specify actual file name

Edit as follows:

class ChangeNameOfCustomers < ActiveRecord::Migration
  def up
    remove_column :customers, :name
    add_column    :customers, :first_name,  :string
    add_column    :customers, :last_name,   :string
  end

  def down
    remove_column :products,  :first_name
    remove_column :products,  :last_name
    add_column    :products,  :name,        :string
  end
end

execute migration:
```
$ rake db:migrate
```
Since name column is removed, define name method as follows (see Edgar Model Convention). Validation is also changed to comply this change:
```
class Customer < ActiveRecord::Base
    :
  validates_presence_of :first_name, :last_name
    :
  def name
    (first_name || '?') + ' ' + (last_name || '?')
  end
end
```
NOTE: Because first_name and last_name have nil just after executing this migration, draw '?' when it is nil. When both columns are required field, this method can simply be first_name + ' ' + last_name.
Reload your browser and see Customer screen.
You can see Customer popup window at the page which model refers customer, for example 'Questions' page form.

[+] [-] 3.2. Change page design and/or layout

If you feel current Edgar web design is not good (maybe yes...), you can change layout(app/views/layout/*) and/or stylesheet(app/assets/stylesheets/*).

[+] [-] 3.3. Select displayed columns

Model, view, and controller, which are generated by edgar:scaffold, can be customized as you want.

This section shows the easiest step, to select displayed columns. Please refer later sections for further customization (e.g. put calculated field, customize view, ...).

You see all of columns at list, form, search-form, and popup (when the model is referred by 'belongs_to') just after executing edgar:scaffold(*) Some columns are not necessary to display for the app. The DB defined column order may be not suitable. Edgar provides easy way to fix this level of customize at the sections below.

(*) Precisely to say, form doesn't show id, created_at, and updated_at.

[+] [-] 3.3.1. Define default model columns and orders for all views

You can overwrite class method 'view_columns()', which should return array of string, to specify which columns to be displayed in which order for all of the model's partial-templates (list, form, search-form, and popup-list). Example:

class Product < ActiveRecord::Base
    :
  def self.view_columns
    %w(id name)
  end
    :
end

[+] [-] 3.3.2. Define model columns and orders for each partial template

4 partial-templates, which are list, form, search-form, and popup-list, are controlled by EdgarController and EdgarPopupController. When you would like to define columns to be displayed and its order for each partial-template, overwrite class methods as follows:

view_list_columns() for list
view_form_columns() for form
view_search_form_columns() for search form
view_popup_columns() for popup

Each method should return string array as the same as view_columns(). User model shows the actual example as:

class User < ActiveRecord::Base
    :
  # overwrite AR::Base.view_list_columns()
  def self.view_list_columns
    %w(id login email created_at updated_at)
  end
    :
end

At ActiveRecord::Base, view_X_columns(), where X is list, form, ..., defines to call view_columns() as the default. So, total 5 methods are used as following priority:

When default model column and its order in all partial-templates are ok, do nothing.
When you would like to define page-wide default column and its order, overwrite view_columns().
(For example) when want to overwrite popup only, overwrite view_popup_columns(). Others (form, list, search-form) are the same.

After customized, please confirm if the program has no bug by:

$ rake test

[+] [-] 3.4. Customize view

When you would like to change screen layout and/or display calculated field, and so on a model, it is not enough to customize at previous section.

This section explains doing so by customize view without any change at controller which inherits from EdgarController.

Edgar:scaffold doesn't generate views because it refers EdgarController's views at default in Edgar plugin as follows (Thank you for Rails3's great feature!):

edgar/_form.html.erb:	form
edgar/_list.html.erb:	list
edgar/_search_form.html.erb:	search form
edgar/index.html.erb:	page

These can be overwritten at each view directory.

[+] [-] 3.4.1. Example

For example, product model specific form view can be set at app/views/products/_form.html.erb, which is automatically used prior to default edgar/_form.html.erb (again, that's Rails-3 feature). The app/views/products/_form.html would be as follows:

...
<%= edgar_form do |f| %>
  <%= draw_form_buttons %>
    <table>
      <tr><th>Name</th>   <td><%= f.text_field :name %></td></tr>
      <tr><th>Price</th>  <td><%= f.text_field :price %></td></tr>
    </table>
<% end %>
...

[+] [-] 3.5. Adding action

When it is not enough to customize view tempmlate, it's now the time to add action for the controller. It is usual activity to develop rails controller action.

[+] [-] 3.6. Inherits from ActionController::Base rather than EdgarController

When the controller doesn't use almost all of EdgarController providing features, it might be good to inherit ActionController::Base and write it own methods. This is normal rails application development rather than Edgar customization.

[+] [-] 4. Test

edgar:scaffold generates functional and unit test. The unit test is the same as plain scaffold, but the functional test is heavily customized and requires Edgar specific test helper and fixtures so that edit test/test_helper.rb as follows:

please add the followings to Gemfile and run 'bundle install':
```
group :test do
  gem 'shoulda-context'
end
```

please add the followings to test/test_helper.rb:

require 'shoulda-context'
Dir[Rails.root + 'edgar2/test/support/**/*.rb'].each { |f| require f }

and include the helper as:

class ActiveSupport::TestCase
  include Edgar::ControllerSupporter
  ...

It reduces time to prepare fixtures for Edgar related models by copying Edgar fixtures to MyApp. Here the steps are:

$ cd edgar2
$ tar cvf /tmp/x.tar test/fixtures/edgar*
$ cd -                        # go back to previous (should be Rails root)
$ tar xvf /tmp/x.tar          # copy edgar2/test/fixtures/edgar/ to test/fixtures/edgar/

There is only one exceptional case which imports fixture file for Edgar::ViewStatus model. Namespaced-non-plural-fixture looks require explicit directive as follows:
```
set_fixture_class edgar_view_status:  'Edgar::ViewStatus'
```

Finally, test/test_helper.rb would become as follows (comment lines are deleted for simplicity):

ENV["RAILS_ENV"] = "test"
require File.expand_path('../../config/environment', __FILE__)
require 'rails/test_help'
require 'shoulda-context'
Dir[Rails.root + 'edgar2/test/support/**/*.rb'].each { |f| require f }

class ActiveSupport::TestCase
  include Edgar::ControllerSupporter
  fixtures :all
  set_fixture_class edgar_view_status:  'Edgar::ViewStatus'
end

Run:
```
$ rake test
```
- Test should pass. If it fails, something is wrong so that please go back the previous step and check.
- You will see many pending tests which are generated by edgar:scaffold. These are up-to-you to modify to fit MyApp spec.

| Generated by juli 1.17.00